home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #5 & #6 / Amiga Plus CD - 1995 - No. 5 and 6.iso / pd / anti-virus / virusz / libs / xfd / xfdmaster.doc < prev   
Text File  |  1995-06-08  |  23KB  |  688 lines
  1. TABLE OF CONTENTS
  2.  
  3. xfdmaster.library/--Overview--
  4. xfdmaster.library/xfdAllocBufferInfo
  5. xfdmaster.library/xfdAllocSegmentInfo
  6. xfdmaster.library/xfdDecrunchBuffer
  7. xfdmaster.library/xfdDecrunchSegment
  8. xfdmaster.library/xfdFreeBufferInfo
  9. xfdmaster.library/xfdFreeSegmentInfo
  10. xfdmaster.library/xfdGetErrorText
  11. xfdmaster.library/xfdRecogBuffer
  12. xfdmaster.library/xfdRecogSegment
  13. xfdmaster.library/xfdRelocate
  14. xfdmaster.library/xfdTestHunkStructure
  15. xfdmaster.library/xfdTestHunkStructureNew
  16. xfdForeman/--Overview--
  17. xfdSlave/--Overview--
  18. xfdSlave/RecogBufferXYZ
  19. xfdSlave/DecrunchBufferXYZ
  20. xfdSlave/RecogSegmentXYZ
  21. xfdSlave/DecrunchSegmentXYZ
  22.  
  23. xfdmaster.library/--Overview--                 xfdmaster.library/--Overview--
  24.  
  25. This section describes the usual way how to use xfdmaster.library from your
  26. own applications.
  27.  
  28. If you want to decrunch files from a buffer, do it like this:
  29.  
  30. 1.  Call xfdAllocBufferInfo(). If not successful, go on with 12.
  31. 2.  Get file size, allocate buffer with that size and load file to buffer.
  32.     If not successful, go on with 10.
  33. 3.  Call xfdRecogBuffer() with xfdbi_SourceBuffer and xfdbi_SourceBufLen
  34.     initialized. If not successful, file is not crunched and you may work
  35.     with that file as it is, release the used memory and go on with 10.
  36. 4.  Check xfdbi_PackerFlags for XFDPFB_PASSWORD or XFDPFB_KEY16/32 (V35),
  37.     go on with 6. if not set.
  38. 5.  Get password (maximum length is stored in xfdbi_MaxSpecialLen) or
  39.     the required 16/32 bit key and store a pointer to it in xfdbi_Special.
  40. 6.  Initialize xfdbi_TargetBufMemType and call xfdDecrunchBuffer(). If not
  41.     successful, work with crunched file, release memory afterwards and
  42.     go on with 10.
  43. 7.  Release memory of xfdbi_SourceBuffer.
  44. 8.  Work with decrunched file.
  45. 9.  Release memory of xfdbi_TargetBuffer.
  46. 10. If you have another file to decrunch, step back to 2.
  47. 11. Call xfdFreeBufferInfo().
  48. 12. Exit!
  49.  
  50. If you want to decrunch a segment list, do it like this:
  51.  
  52. 1.  Call xfdAllocSegmentInfo(). If not successful, go on with 11.
  53. 2.  dos.library/LoadSeg() file. If not successful, go on with 9.
  54. 3.  Call xfdRecogSegment() with xfdsi_SegList initialized. If not
  55.     successful, seglist isn't crunched and you may go on with 7.
  56. 4.  Check xfdsi_PackerFlags for XFDPFB_PASSWORD or XFDPFB_KEY16/32 (V35).
  57.     If set, get password (maximum length is stored in xfdsi_MaxSpecialLen)
  58.     or 16/32 bit key and store a pointer to it in xfdsi_Special.
  59. 5.  (V34) Check xfdsi_PackerFlags for XFDPFB_RELMODE. If set, init
  60.     xfdsi_RelMode with the desired value.
  61. 6.  Call xfdDecrunchSegment(). If not successful, test xfdsi_SegList.
  62.     If this field contains NULL, no seglist is available anymore. You
  63.     have to dos.library/LoadSeg() the file again then.
  64. 7.  Work with segment list.
  65. 8.  dos.library/UnloadSeg() segment list.
  66. 9.  If you have another segment list to decrunch, step back to 2.
  67. 10. Call xfdFreeSegmentInfo().
  68. 11. Exit!
  69.  
  70. Whenever you intend to use a feature of the xfdmaster.library that is
  71. marked (V34) or higher, make sure that you use this version number
  72. during the exec.library/OpenLibrary() call. Otherwise, if you try to
  73. use new features with an old library version, the system might crash.
  74.  
  75. xfdmaster.library/xfdAllocBufferInfo     xfdmaster.library/xfdAllocBufferInfo
  76.  
  77.    NAME
  78.     xfdAllocBufferInfo -- Allocate memory for BufferInfo structure.
  79.  
  80.    SYNOPSIS
  81.     bufferinfo = xfdAllocBufferInfo()
  82.         D0              -30
  83.  
  84.     struct xfdBufferInfo *xfdAllocBufferInfo(void);
  85.  
  86.    FUNCTION
  87.     Allocates a memory block large enough to hold all information of
  88.     the xfdBufferInfo structure. Never do this in any other way for
  89.     compatibility with library updates.
  90.  
  91.    INPUTS
  92.     None.
  93.  
  94.    RESULT
  95.     bufferinfo - Pointer to the xfdBufferInfo structure or NULL if
  96.                  there occured an error.
  97.  
  98.    SEE ALSO
  99.     xfdFreeBufferInfo()
  100.  
  101. xfdmaster.library/xfdAllocSegmentInfo   xfdmaster.library/xfdAllocSegmentInfo
  102.  
  103.    NAME
  104.     xfdAllocSegmentInfo -- Allocate memory for SegmentInfo structure.
  105.  
  106.    SYNOPSIS
  107.     segmentinfo = xfdAllocSegmentInfo()
  108.         D0                -42
  109.  
  110.     struct xfdSegmentInfo *xfdAllocSegmentInfo(void);
  111.  
  112.    FUNCTION
  113.     Allocates a memory block large enough to hold all information of
  114.     the xfdSegmentInfo structure. Never do this in any other way for
  115.     compatibility with library updates.
  116.  
  117.    INPUTS
  118.     None.
  119.  
  120.    RESULT
  121.     segmentinfo - Pointer to the xfdSegmentInfo structure or NULL if
  122.                   there occured an error.
  123.  
  124.    SEE ALSO
  125.     xfdFreeSegmentInfo()
  126.  
  127. xfdmaster.library/xfdDecrunchBuffer       xfdmaster.library/xfdDecrunchBuffer
  128.  
  129.    NAME
  130.     xfdDecrunchBuffer -- Decrunch a file from buffer.
  131.  
  132.    SYNOPSIS
  133.     success = xfdDecrunchBuffer(bufferinfo)
  134.       D0             -60            A0
  135.  
  136.     BOOL xfdDecrunchBuffer(struct xfdBufferInfo *);
  137.  
  138.    FUNCTION
  139.     Decrunches a file to a separate buffer. You have to call
  140.     xfdRecogBuffer() first, only if this call was successful,
  141.     you may call xfdDecrunchBuffer().
  142.  
  143.     You have to pass the type of memory that should be used for
  144.     the target buffer in xfdbi_TargetBufMemType.
  145.     Additionally you have to init the xfdbi_Special field with
  146.     a pointer to a special info buffer if any special flags are
  147.     set in the xfdbi_PackerFlags field:
  148.     XFDPFB_PASSWORD    - Buffer contains password (max. length of
  149.                          password is stored in xfdbi_MaxSpecialLen).
  150.     XFDPFB_KEY16 (V35) - xfdbi_Special points to an UWORD that holds
  151.                          a 16 bit key.
  152.     XFDPFB_KEY32 (V35) - xfdbi_Special points to an ULONG that holds
  153.                          a 32 bit key.
  154.  
  155.     If the decrunching was successful, the following fields in
  156.     the xfdBufferInfo structure will be initialized:
  157.  
  158.     xfdbi_TargetBuffer     - Pointer to decrunched file buffer.
  159.     xfdbi_TargetBufSaveLen - Length of decrunched file (for saving etc.).
  160.     xfdbi_TargetBufLen     - Total length of allocated buffer.
  161.     xfdbi_DecrAddress      - If XFDPFB_ADDR is set in xfdbi_PackerFlags,
  162.                              this contains the address where the crunched
  163.                              file has been relocated to.
  164.     xfdbi_JmpAddress       - If XFDPFB_ADDR is set in xfdbi_PackerFlags,
  165.                              this contains the address where to jump at
  166.                              in order to run the file.
  167.  
  168.    INPUTS
  169.     bufferinfo - Pointer to an initialized xfdBufferInfo structure:
  170.        xfdbi_TargetBufMemType - Type of memory for target buffer.
  171.        xfdbi_Special          - Pointer to special info if required.
  172.  
  173.    RESULT
  174.     success - TRUE if decrunching was successful, FALSE if
  175.               anything went wrong.
  176.  
  177.    NOTE
  178.     xfdDecrunchBuffer() allocates a buffer for the decrunched file,
  179.     but it doesn't release this memory afterwards. That is because
  180.     you first have to work with the decrunched file (what else?).
  181.     Therefore you have to do a call to exec.library/FreeMem() after
  182.     you finished work. Use the following parameters:
  183.     xfdbi_TargetBufLen - Lenght of buffer.
  184.     xfdbi_TargetBuffer - Pointer to buffer.
  185.  
  186.     Don't forget:
  187.     xfdbi_TargetBufLen contains the length of the allocated memory
  188.     area, xfdbi_TargetBufSaveLen the length of the decrunched file
  189.     in that buffer.
  190.  
  191.     xfdDecrunchBuffer() never touches the buffer that contains the
  192.     crunched file. It's again your task to release this after
  193.     decrunching.
  194.  
  195.    SEE ALSO
  196.     xfdRecogBuffer(), exec.library/FreeMem()
  197.  
  198. xfdmaster.library/xfdDecrunchSegment     xfdmaster.library/xfdDecrunchSegment
  199.  
  200.    NAME
  201.     xfdDecrunchSegment -- Decrunch a file from its segment list.
  202.  
  203.    SYNOPSIS
  204.     success = xfdDecrunchSegment(segmentinfo)
  205.       D0             -72             A0
  206.  
  207.     BOOL xfdDecrunchSegment(struct xfdSegmentInfo *);
  208.  
  209.    FUNCTION
  210.     Decrunches a segment list. You have to call xfdRecogSegment()
  211.     first, only if this call was successful, you may call
  212.     xfdDecrunchSegment().
  213.  
  214.     You have to init the xfdsi_Special field with a pointer to a
  215.     special info buffer if any special flags are set in the
  216.     xfdsi_PackerFlags field:
  217.     XFDPFB_PASSWORD    - Buffer contains password (max. length of
  218.                          password is stored in xfdsi_MaxSpecialLen).
  219.     XFDPFB_KEY16 (V35) - xfdsi_Special points to an UWORD that holds
  220.                          a 16 bit key.
  221.     XFDPFB_KEY32 (V35) - xfdsi_Special points to an ULONG that holds
  222.                          a 32 bit key.
  223.  
  224.     (V34) Check xfdsi_Packerflags for XFDPFB_RELMODE. If set,
  225.     initialize xfdsi_RelMode with the desired XFDREL_#? value.
  226.  
  227.     If decrunching was successful, xfdsi_SegList holds a BPTR to
  228.     the decrunched segment list. The old segment list has been
  229.     released and/or replaced by the new one (depends on cruncher).
  230.  
  231.     If decrunching failed, xfdsi_SegList may be NULL. This happens
  232.     if an error occured after the seglist has already been changed
  233.     in any way. It then will be released.
  234.     Otherwise, if xfdsi_SegList is not NULL, it still contains a
  235.     valid BPTR to the crunched segment list.
  236.  
  237.    INPUTS
  238.     segmentinfo - Pointer to an initialized xfdSegmentInfo structure:
  239.        xfdsi_Special - Pointer to special info if required.
  240.        xfdsi_RelMode - (V34) XFDREL_#? value if required.
  241.  
  242.    RESULT
  243.     success - TRUE if decrunching was successful, FALSE if
  244.               anything went wrong.
  245.  
  246.    NOTE
  247.     If you no longer need the decrunched segment list, you may
  248.     release it by simply calling dos.library/UnloadSeg().
  249.  
  250.    SEE ALSO
  251.     xfdRecogSegment(), dos.library/UnloadSeg()
  252.  
  253. xfdmaster.library/xfdFreeBufferInfo       xfdmaster.library/xfdFreeBufferInfo
  254.  
  255.    NAME
  256.     xfdFreeBufferInfo -- Free memory of xfdBufferInfo structure.
  257.  
  258.    SYNOPSIS
  259.     xfdFreeBufferInfo(bufferinfo)
  260.            -36            A1
  261.  
  262.     void xfdFreeBufferInfo(struct xfdBufferInfo *);
  263.  
  264.    FUNCTION
  265.     Deallocates the memory reserved via xfdAllocBufferInfo().
  266.  
  267.    INPUTS
  268.     bufferinfo - Pointer to xfdBufferInfo structure.
  269.  
  270.    RESULT
  271.     None.
  272.  
  273.    SEE ALSO
  274.     xfdAllocBufferInfo()
  275.  
  276. xfdmaster.library/xfdFreeSegmentInfo     xfdmaster.library/xfdFreeSegmentInfo
  277.  
  278.    NAME
  279.     xfdFreeSegmentInfo -- Free memory of xfdSegmentInfo structure.
  280.  
  281.    SYNOPSIS
  282.     xfdFreeSegmentInfo(segmentinfo)
  283.            -48             A1
  284.  
  285.     void xfdFreeSegmentInfo(struct xfdSegmentInfo *);
  286.  
  287.    FUNCTION
  288.     Deallocates the memory reserved via xfdAllocSegmentInfo().
  289.  
  290.    INPUTS
  291.     segmentinfo - Pointer to xfdSegmentInfo structure.
  292.  
  293.    RESULT
  294.     None.
  295.  
  296.    SEE ALSO
  297.     xfdAllocSegmentInfo()
  298.  
  299. xfdmaster.library/xfdGetErrorText           xfdmaster.library/xfdGetErrorText
  300.  
  301.    NAME
  302.     xfdGetErrorText -- Get an ascii string from an error number.
  303.  
  304.    SYNOPSIS
  305.     string = xfdGetErrorText(error)
  306.       D0           -78        D0.w
  307.  
  308.     STRPTR xfdGetErrorText(UWORD);
  309.  
  310.    FUNCTION
  311.     Whenever a library call fails, you receive an error number either
  312.     in the xfd#?_Error field or directly as a returncode. This function
  313.     gets the corresponding ascii string to the occured error.
  314.  
  315.    INPUTS
  316.     error - Error number from xfd#?_Error or returncode.
  317.  
  318.    RESULT
  319.     string - Pointer to an ascii string that describes the error.
  320.  
  321.    SEE ALSO
  322.     xfdDecrunchBuffer(), xfdDecrunchSegment(), xfdRelocate(),
  323.     xfdTestHunkStructureNew()
  324.  
  325. xfdmaster.library/xfdRecogBuffer             xfdmaster.library/xfdRecogBuffer
  326.  
  327.    NAME
  328.     xfdRecogBuffer -- Examine buffer for crunched file.
  329.  
  330.    SYNOPSIS
  331.     success = xfdRecogBuffer(bufferinfo)
  332.       D0             -54         A0
  333.  
  334.     BOOL xfdRecogBuffer(struct xfdBufferInfo *);
  335.  
  336.    FUNCTION
  337.     Examines a file for known crunchers. You pass a pointer to
  338.     the file buffer in xfdbi_SourceBuffer and the length of the
  339.     buffer in xfdbi_SourceBufLen.
  340.  
  341.     If a crunched file has been recognized, the following fields
  342.     in the xfdBufferInfo structure will be initialized:
  343.  
  344.     xfdbi_PackerName    - Pointer to the name of the cruncher.
  345.     xfdbi_PackerFlags   - Contains the packer type and additional
  346.                           information (eg. password).
  347.     xfdbi_MaxSpecialLen - Only used if any special flags are set.
  348.  
  349.    INPUTS
  350.     bufferinfo - Pointer to an initialized xfdBufferInfo structure:
  351.        xfdbi_SourceBuffer - Pointer to file buffer.
  352.        xfdbi_SourceBufLen - Length of file buffer.
  353.  
  354.    RESULT
  355.     success - TRUE if a cruncher has been recognized, FALSE if
  356.               file is unknown.
  357.  
  358.    SEE ALSO
  359.     xfdDecrunchBuffer()
  360.  
  361. xfdmaster.library/xfdRecogSegment           xfdmaster.library/xfdRecogSegment
  362.  
  363.    NAME
  364.     xfdRecogSegment -- Examine segment list for crunched file.
  365.  
  366.    SYNOPSIS
  367.     success = xfdRecogSegment(segmentinfo)
  368.       D0             -66          A0
  369.  
  370.     BOOL xfdRecogSegment(struct xfdSegmentInfo *);
  371.  
  372.    FUNCTION
  373.     Examines a segment list for known crunchers. You pass a BPTR
  374.     to the segment list in xfdsi_SegList.
  375.  
  376.     If a crunched segment list has been recognized, the following
  377.     fields in the xfdSegmentInfo structure will be initialized:
  378.  
  379.     xfdsi_PackerName    - Pointer to the name of the cruncher.
  380.     xfdsi_PackerFlags   - Contains the packer type and additional
  381.                           information (eg. password).
  382.     xfdsi_MaxSpecialLen - Only used if any special flags are set.
  383.  
  384.    INPUTS
  385.     segmentinfo - Pointer to an initialized xfdSegmentInfo structure:
  386.        xfdsi_SegList - BPTR to segment list.
  387.  
  388.    RESULT
  389.     success - TRUE if a cruncher has been recognized, FALSE if
  390.               segment list is unknown.
  391.  
  392.    SEE ALSO
  393.     xfdDecrunchSegment()
  394.  
  395. xfdmaster.library/xfdRelocate                   xfdmaster.library/xfdRelocate
  396.  
  397.    NAME
  398.     xfdRelocate -- Create segment list from file buffer. (V34)
  399.  
  400.    SYNOPSIS
  401.     error = xfdRelocate(buffer, length, result, mode)
  402.      D0.w       -96       A0      D0      A1    D1.w
  403.  
  404.     UWORD xfdRelocate(APTR, ULONG, ULONG *, UWORD);
  405.  
  406.    FUNCTION
  407.     Creates a relocated and fully executable segment list from
  408.     a file buffer. The result is a BPTR to the first segment,
  409.     similar to the result of a call to dos.library/LoadSeg().
  410.  
  411.    INPUTS
  412.     buffer - Pointer to the file buffer that should be relocated.
  413.     length - Length of the file buffer.
  414.     result - Pointer to the longword that should hold the result.
  415.     mode   - Any XFDREL_#? relocation mode.
  416.  
  417.    RESULT
  418.     error  - XFDERR_OK if no error occured, else XFDERR_#?.
  419.     result - Holds a BPTR to the first segment if error = XFDERR_OK.
  420.  
  421.    NOTE
  422.     There is no need to call xfdTestHunkStructure[New]() before
  423.     relocation because xfdRelocate() does this already.
  424.  
  425.     This routine supports the following hunk types:
  426.     - hunk_unit    ($3e7) -> Skipped.
  427.     - hunk_name    ($3e8) -> Skipped.
  428.     - hunk_code    ($3e9) -> Creates new code segment.
  429.     - hunk_data    ($3ea) -> Creates new data segment.
  430.     - hunk_bss     ($3eb) -> Creates new bss segment.
  431.     - hunk_reloc32 ($3ec) -> Used for relocation.
  432.     - hunk_ext     ($3ef) -> Skipped.
  433.     - hunk_symbol  ($3f0) -> Skipped.
  434.     - hunk_debug   ($3f1) -> Skipped.
  435.     - hunk_end     ($3f2) -> May be left out.
  436.     Any other hunk types create an error. There is no support for
  437.     hunk_overlay, because the main purpose of this routine is to
  438.     be called from xfds_DecrunchSegment. And in that case, the real
  439.     dos.library/LoadSeg() has already initialized the overlay header.
  440.  
  441. xfdmaster.library/xfdTestHunkStructure xfdmaster.library/xfdTestHunkStructure
  442.  
  443.    NAME
  444.     xfdTestHunkStructure -- Test hunks of executable file.
  445.  
  446.    SYNOPSIS
  447.     success = xfdTestHunkStructure(buffer, length)
  448.       D0              -84            A0      D0
  449.  
  450.     BOOL xfdTestHunkStructure(APTR, ULONG);
  451.  
  452.    FUNCTION
  453.     Checks an executable file for a valid hunk structure.
  454.     This is important for decrunching files, because an incomplete
  455.     or damaged file may cause a system crash.
  456.  
  457.    INPUTS
  458.     buffer - Pointer to the file buffer that should be checked.
  459.     length - Length of the file buffer.
  460.  
  461.    RESULT
  462.     success - TRUE if file is ok, FALSE if file is damaged.
  463.  
  464.    SEE ALSO
  465.     xfdTestHunkStructureNew()
  466.  
  467. xfdmaster.lib/xfdTestHunkStructureNew   xfdmaster.lib/xfdTestHunkStructureNew
  468.  
  469.    NAME
  470.     xfdTestHunkStructureNew -- Test hunks of executable file. (V34)
  471.  
  472.    SYNOPSIS
  473.     error = xfdTestHunkStructureNew(buffer, length)
  474.      D0.w           -90               A0      D0
  475.  
  476.     UWORD xfdTestHunkStructureNew(APTR, ULONG);
  477.  
  478.    FUNCTION
  479.     Checks an executable file for a valid hunk structure.
  480.     This is important for decrunching files, because an incomplete
  481.     or damaged file may cause a system crash.
  482.  
  483.    INPUTS
  484.     buffer - Pointer to the file buffer that should be checked.
  485.     length - Length of the file buffer.
  486.  
  487.    RESULT
  488.     error - XFDERR_OK if file is ok, XFDERR_#? if file is damaged.
  489.  
  490.    NOTE
  491.     You don't have to call this function before trying to decrunch
  492.     a file, because xfdDecrunchBuffer() does this already.
  493.  
  494.     This hunk checker supports all standard hunk types from
  495.     hunk_unit ($3e7) to hunk_index ($3fb).
  496.     It recognizes the standard hunk_overlay ($3f5) format and some
  497.     user-defined overlay types too. Anyway, it may happen that some
  498.     weird overlay hunk causes problems because there isn't any real
  499.     definition for overlays.
  500.     The hunk structure of a non-overlayed file will nevertheless
  501.     be checked 100% correctly.
  502.  
  503.    SEE ALSO
  504.     xfdTestHunkStructure()
  505.  
  506. xfdForeman/--Overview--                               xfdForeman/--Overview--
  507.  
  508. The xfdForeman structure is just some kind of header for external slaves.
  509. It protects the slaves from being executed accidentally by having a small
  510. piece of code (moveq #-1,d0 : rts) in the first 4 bytes.
  511. The master can identify a valid bunch of external slaves by checking the
  512. first few bytes of the file for the foreman identification.
  513. Finally, a foreman holds the pointer to a linked list of slaves and thus
  514. enables the master to work with these slaves.
  515.  
  516. xfdSlave/--Overview--                                   xfdSlave/--Overview--
  517.  
  518. The xfdSlave structure is the heart of the whole library system. Each slave
  519. enables the master to recognize and decrunch packed files and/or segments.
  520.  
  521. Therefore each slave contains 4 routines that are called from the master.
  522. Pointers to these routines are stored in xfds_Recog#? and xfds_Decrunch#?.
  523. All have one thing in common: the CPU registers D0/D1/A0/A1 are so called
  524. scratch registers, they may change during execution, all other registers
  525. must remain unchanged. CPU register A6 holds a pointer to the xfdMasterBase
  526. structure. See chapters below for a description of the slave routines.
  527.  
  528. ALL SLAVE ROUTINES MUST BE REENTRANT! NEVER STORE ANY DATA IN STATIC MEMORY
  529. AREAS, USE THE STACK OR SOME ALLOCATED MEMORY INSTEAD! REMEMBER THAT THE
  530. ROUTINES MIGHT BE CALLED BY SEVERAL PROGRAMS AT THE SAME TIME!
  531.  
  532. The name of the packer that is supported by the slave and the flags that
  533. describe the packer are stored in xfds_PackerName and xfds_PackerFlags.
  534.  
  535. Whenever you intend to use features of the xfdmaster.library in your slaves
  536. that are marked (V34) or higher, make sure to set xfds_MasterVersion to
  537. the desired version number, otherwise an old library version might crash
  538. while using the new slave.
  539.  
  540. xfdSlave/RecogBufferXYZ                               xfdSlave/RecogBufferXYZ
  541.  
  542.    NAME
  543.     RecogBufferXYZ -- Recognize crunched file in buffer.
  544.  
  545.    SYNOPSIS
  546.     result = RecogBufferXYZ(buffer, length)
  547.       D0                      A0      D0
  548.  
  549.     BOOL RecogBufferXYZ(APTR, ULONG);
  550.  
  551.    FUNCTION
  552.     This routine should examine the buffer for a crunched file.
  553.     First thing is to check if the size of the file allows it to
  554.     be crunched with the packer in question. After that, simply
  555.     do some compares to figure out if the file has been crunched
  556.     or not.
  557.  
  558.    INPUTS
  559.     buffer - Pointer to a buffer that holds the crunched file.
  560.     length - Length of that buffer.
  561.  
  562.    RESULT
  563.     result - TRUE if packer has been recognized, else FALSE.
  564.  
  565.    NOTE
  566.     You have to initialize xfds_RecogBuffer with a pointer to your
  567.     RecogBufferXYZ routine.
  568.  
  569.    SEE ALSO
  570.     Example sourcecodes.
  571.  
  572. xfdSlave/DecrunchBufferXYZ                         xfdSlave/DecrunchBufferXYZ
  573.  
  574.    NAME
  575.     DecrunchBufferXYZ -- Decrunch file from buffer to buffer.
  576.  
  577.    SYNOPSIS
  578.     result = DecrunchBufferXYZ(bufferinfo)
  579.       D0                           A0
  580.  
  581.     BOOL DecrunchBufferXYZ(struct xfdBufferInfo *);
  582.  
  583.    FUNCTION
  584.     The typical steps of such a routine are:
  585.     - Get length of decrunched file (exactly or a bit too much).
  586.     - Allocate memory (with memtype from xfdbi_TargetBufMemType).
  587.     - Decrunch file from xfdbi_SourceBuffer to xfdbi_TargetBuffer.
  588.     - Initialize all necessary parts of the xfdBufferInfo structure.
  589.     - Set xfdbi_Error if an error occurs.
  590.  
  591.    INPUTS
  592.     bufferinfo - A valid xfdBufferInfo structure that successfully went
  593.                  through a call to xfdRecogBuffer().
  594.  
  595.    RESULT
  596.     result - TRUE if decrunching succeeded, FALSE if something went wrong.
  597.  
  598.    NOTE
  599.     You have to initialize xfds_DecrunchBuffer with a pointer to your
  600.     DecrunchBufferXYZ routine.
  601.  
  602.    SEE ALSO
  603.     Example sourcecodes.
  604.  
  605. xfdSlave/RecogSegmentXYZ                             xfdSlave/RecogSegmentXYZ
  606.  
  607.    NAME
  608.     RecogSegmentXYZ -- Recognize crunched segment list.
  609.  
  610.    SYNOPSIS
  611.     result = RecogSegmentXYZ(seglist)
  612.       D0                       A0
  613.  
  614.     BOOL RecogSegmentXYZ(BPTR);
  615.  
  616.    FUNCTION
  617.     This routine should examine if a segment list is crunched.
  618.     You can check the whole segment list for correct lengths of hunks
  619.     and for contents of hunks if you like. There should be at least
  620.     3 comparations to determine the cruncher.
  621.  
  622.    INPUTS
  623.     seglist - BPTR to first segment.
  624.  
  625.    RESULT
  626.     result - TRUE if packer has been recognized, else FALSE.
  627.  
  628.    NOTE
  629.     You have to initialize xfds_RecogSegment with a pointer to your
  630.     RecogSegmentXYZ routine.
  631.  
  632.    SEE ALSO
  633.     Example sourcecodes.
  634.  
  635. xfdSlave/DecrunchSegmentXYZ                       xfdSlave/DecrunchSegmentXYZ
  636.  
  637.    NAME
  638.     DecrunchSegmentXYZ -- Decrunch segment list.
  639.  
  640.    SYNOPSIS
  641.     result = DecrunchSegmentXYZ(segmentinfo)
  642.       D0                             A0
  643.  
  644.     BOOL DecrunchSegmentXYZ(struct xfdSegmentInfo *);
  645.  
  646.    FUNCTION
  647.     There are two possibilities how to decrunch a segment list. The
  648.     first one works like this:
  649.     - Modify decrunch header to make it return to the caller.
  650.     - Call decrunch header.
  651.     - dos.library/UnloadSeg() whole seglist and clear xfdsi_SegList
  652.       if an error occurs and the seglist has already been altered
  653.       in any way.
  654.     - Otherwise only release segments that are no longer necessary.
  655.     - Store BPTR to first hunk of decrunched segment list in
  656.       xfdsi_SegList.
  657.     - Set xfdsi_Error if an error occurs.
  658.  
  659.     The second possibility works the same way as the first with
  660.     the difference that you don't jump to the original code, but you
  661.     include all necessary parts of it (decrunch routine, relocator)
  662.     in your own routine. The big advantage is that you can handle
  663.     error conditions much better because most of the standard decrunch
  664.     headers in executable files have problems with low memory etc.
  665.  
  666.     (V34) If the decruncher allows it, always support XFDPFB_RELMODE.
  667.     That way the caller can determine the type of memory the segments
  668.     should be placed in by initializing xfdsi_RelMode with XFDREL_#?.
  669.  
  670.     Many crunchers don't change the hunk structure of the crunched
  671.     data. If this is the case, you can simply call the decrunch code
  672.     in the segment list and then use xfdRelocate() (V34).
  673.  
  674.    INPUTS
  675.     segmentinfo - A valid xfdSegmentInfo structure that successfully went
  676.                   through a call to xfdRecogSegment().
  677.  
  678.    RESULT
  679.     result - TRUE if decrunching succeeded, FALSE if something went wrong.
  680.  
  681.    NOTE
  682.     You have to initialize xfds_DecrunchSegment with a pointer to your
  683.     DecrunchSegmentXYZ routine.
  684.  
  685.    SEE ALSO
  686.     Example sourcecodes.
  687.  
  688.